home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / perl5 / Path / Class.pm
Encoding:
Perl POD Document  |  2010-06-07  |  5.0 KB  |  178 lines
  1. package Path::Class;
  2.  
  3. $VERSION = '0.19';
  4. @ISA = qw(Exporter);
  5. @EXPORT    = qw(file dir);
  6. @EXPORT_OK = qw(file dir foreign_file foreign_dir);
  7.  
  8. use strict;
  9. use Exporter;
  10. use Path::Class::File;
  11. use Path::Class::Dir;
  12.  
  13. sub file { Path::Class::File->new(@_) }
  14. sub dir  { Path::Class::Dir ->new(@_) }
  15. sub foreign_file { Path::Class::File->new_foreign(@_) }
  16. sub foreign_dir  { Path::Class::Dir ->new_foreign(@_) }
  17.  
  18.  
  19. 1;
  20. __END__
  21.  
  22. =head1 NAME
  23.  
  24. Path::Class - Cross-platform path specification manipulation
  25.  
  26. =head1 SYNOPSIS
  27.  
  28.   use Path::Class;
  29.   
  30.   my $dir  = dir('foo', 'bar');       # Path::Class::Dir object
  31.   my $file = file('bob', 'file.txt'); # Path::Class::File object
  32.   
  33.   # Stringifies to 'foo/bar' on Unix, 'foo\bar' on Windows, etc.
  34.   print "dir: $dir\n";
  35.   
  36.   # Stringifies to 'bob/file.txt' on Unix, 'bob\file.txt' on Windows
  37.   print "file: $file\n";
  38.   
  39.   my $subdir  = $dir->subdir('baz');  # foo/bar/baz
  40.   my $parent  = $subdir->parent;      # foo/bar
  41.   my $parent2 = $parent->parent;      # foo
  42.   
  43.   my $dir2 = $file->dir;              # bob
  44.  
  45.   # Work with foreign paths
  46.   use Path::Class qw(foreign_file foreign_dir);
  47.   my $file = foreign_file('Mac', ':foo:file.txt');
  48.   print $file->dir;                   # :foo:
  49.   print $file->as_foreign('Win32');   # foo\file.txt
  50.   
  51.   # Interact with the underlying filesystem:
  52.   
  53.   # $dir_handle is an IO::Dir object
  54.   my $dir_handle = $dir->open or die "Can't read $dir: $!";
  55.   
  56.   # $file_handle is an IO::File object
  57.   my $file_handle = $file->open($mode) or die "Can't read $file: $!";
  58.  
  59. =head1 DESCRIPTION
  60.  
  61. C<Path::Class> is a module for manipulation of file and directory
  62. specifications (strings describing their locations, like
  63. C<'/home/ken/foo.txt'> or C<'C:\Windows\Foo.txt'>) in a cross-platform
  64. manner.  It supports pretty much every platform Perl runs on,
  65. including Unix, Windows, Mac, VMS, Epoc, Cygwin, OS/2, and NetWare.
  66.  
  67. The well-known module C<File::Spec> also provides this service, but
  68. it's sort of awkward to use well, so people sometimes avoid it, or use
  69. it in a way that won't actually work properly on platforms
  70. significantly different than the ones they've tested their code on.
  71.  
  72. In fact, C<Path::Class> uses C<File::Spec> internally, wrapping all
  73. the unsightly details so you can concentrate on your application code.
  74. Whereas C<File::Spec> provides functions for some common path
  75. manipulations, C<Path::Class> provides an object-oriented model of the
  76. world of path specifications and their underlying semantics.
  77. C<File::Spec> doesn't create any objects, and its classes represent
  78. the different ways in which paths must be manipulated on various
  79. platforms (not a very intuitive concept).  C<Path::Class> creates
  80. objects representing files and directories, and provides methods that
  81. relate them to each other.  For instance, the following C<File::Spec>
  82. code:
  83.  
  84.  my $absolute = File::Spec->file_name_is_absolute(
  85.                   File::Spec->catfile( @dirs, $file )
  86.                 );
  87.  
  88. can be written using C<Path::Class> as
  89.  
  90.  my $absolute = Path::Class::File->new( @dirs, $file )->is_absolute;
  91.  
  92. or even as 
  93.  
  94.  my $absolute = file( @dirs, $file )->is_absolute;
  95.  
  96. Similar readability improvements should happen all over the place when
  97. using C<Path::Class>.
  98.  
  99. Using C<Path::Class> can help solve real problems in your code too -
  100. for instance, how many people actually take the "volume" (like C<C:>
  101. on Windows) into account when writing C<File::Spec>-using code?  I
  102. thought not.  But if you use C<Path::Class>, your file and directory objects
  103. will know what volumes they refer to and do the right thing.
  104.  
  105. The guts of the C<Path::Class> code live in the C<Path::Class::File>
  106. and C<Path::Class::Dir> modules, so please see those
  107. modules' documentation for more details about how to use them.
  108.  
  109. =head2 EXPORT
  110.  
  111. The following functions are exported by default.
  112.  
  113. =over 4
  114.  
  115. =item file
  116.  
  117. A synonym for C<< Path::Class::File->new >>.
  118.  
  119. =item dir
  120.  
  121. A synonym for C<< Path::Class::Dir->new >>.
  122.  
  123. =back
  124.  
  125. If you would like to prevent their export, you may explicitly pass an
  126. empty list to perl's C<use>, i.e. C<use Path::Class ()>.
  127.  
  128. The following are exported only on demand.
  129.  
  130. =over 4
  131.  
  132. =item foreign_file
  133.  
  134. A synonym for C<< Path::Class::File->new_foreign >>.
  135.  
  136. =item foreign_dir
  137.  
  138. A synonym for C<< Path::Class::Dir->new_foreign >>.
  139.  
  140. =back
  141.  
  142. =head1 Notes on Cross-Platform Compatibility
  143.  
  144. Although it is much easier to write cross-platform-friendly code with
  145. this module than with C<File::Spec>, there are still some issues to be
  146. aware of.
  147.  
  148. =over 4
  149.  
  150. =item *
  151.  
  152. Some platforms, notably VMS and some older versions of DOS (I think),
  153. all filenames must have an extension.  Thus if you create a file
  154. called F<foo/bar> and then ask for a list of files in the directory
  155. F<foo>, you may find a file called F<bar.> instead of the F<bar> you
  156. were expecting.  Thus it might be a good idea to use an extension in
  157. the first place.
  158.  
  159. =back
  160.  
  161. =head1 AUTHOR
  162.  
  163. Ken Williams, KWILLIAMS@cpan.org
  164.  
  165. =head1 COPYRIGHT
  166.  
  167. Copyright (c) Ken Williams.  All rights reserved.
  168.  
  169. This library is free software; you can redistribute it and/or
  170. modify it under the same terms as Perl itself.
  171.  
  172.  
  173. =head1 SEE ALSO
  174.  
  175. Path::Class::Dir, Path::Class::File, File::Spec
  176.  
  177. =cut
  178.